Skip to content

Add JSDoc documentation for JSR symbol pages#13

Draft
Copilot wants to merge 4 commits intomainfrom
copilot/add-symbol-documentation
Draft

Add JSDoc documentation for JSR symbol pages#13
Copilot wants to merge 4 commits intomainfrom
copilot/add-symbol-documentation

Conversation

Copy link
Contributor

Copilot AI commented Oct 29, 2025

JSR symbol pages were empty because exported members lacked JSDoc annotations. Added comprehensive documentation to all 112+ exported symbols across the codebase.

Changes

Core modules

  • slice.ts — Slice class, make(), append()
  • defer.ts — DeferredSyncFunc/AsyncFunc types, scope()
  • channel.ts — Channel class, select(), ReceiveCase/SendCase/DefaultCase interfaces

Submodules

  • context/* — Context interface, all factory functions (withCancel, withTimeout, etc.), error classes
  • sync/cond.ts — Cond class with usage examples
  • io/* — Reader, Writer, Closer interface methods
  • bytes/* — Buffer class and 40+ utility functions (search, transform, split/join, trim)

Format

Documentation follows JSR guidelines:

  • One-sentence summaries starting with verbs
  • @param, @returns, @example tags where applicable
  • GoDoc-like tone (concise, factual)
/**
 * Creates a cancellable Context derived from parent.
 * Similar to Go's context.WithCancel.
 *
 * @param parent - The parent Context
 * @returns A tuple of [Context, CancelFunc]
 *
 * @example
 * ```ts
 * const [ctx, cancel] = context.withCancel(context.background());
 * // ... do work
 * cancel();
 * ```
 */
export function withCancel(parent: Context): [Context, CancelFunc]

All modules now pass deno doc --lint with zero errors.

Original prompt

This section details on the original issue you should resolve

<issue_title>[FEATURE] Add Symbol Documentation</issue_title>
<issue_description>### Overview

We will enhance the documentation of @okudai/golikejs by adding JSR-compatible symbol documentation for each exported function, class, and constant.
This will ensure that all symbols are properly displayed and described on JSR’s documentation site.

Motivation & Benefits

Currently, the JSR documentation only displays the package overview, and the symbol pages are empty because exported members lack proper JSDoc annotations.
Adding rich symbol documentation will:

  • Improve discoverability and usability of each API
  • Provide Go-like structured explanations for functions and packages
  • Make the JSR page a more complete and professional reference for developers

Use Case

When users visit the JSR page for @okudai/golikejs, they should be able to:

  • View a clear explanation for each exported symbol (e.g., bytes.Clone, strings.ToTitle, etc.)
  • Understand the purpose, parameters, and return values through JSDoc-formatted descriptions
  • Use the documentation as an API reference similar to GoDoc

Proposed Solution (include Next Steps)

  1. Add JSDoc-style comments to all exported symbols following the JSR Symbol Documentation Guide.
  2. Include @param, @returns, and @example tags for key functions.
  3. Run deno doc --lint locally to verify formatting and coverage.
  4. Publish a new version to confirm that symbol pages are properly generated on JSR.
  5. Optionally, add examples and type definitions where needed.

Alternatives Considered

  • Relying only on README-level documentation (insufficient for per-symbol clarity).
  • Generating docs manually via deno doc output (not integrated with JSR’s UI).

Checklist

  • I have searched existing issues
  • I have read relevant documentation
  • I can contribute to this feature</issue_description>

<agent_instructions># Context
This repository implements @okudai/golikejs, a JavaScript/TypeScript library that brings Go-like standard packages and coding style to JS/TS environments.
It re-implements core parts of Go’s standard library, such as:

  • bytes
  • strings
  • fmt
  • io
  • time
    and provides idiomatic Go-like APIs for JavaScript developers.

The project targets pure Deno and aims for compatibility with JSR.
It is meant to feel like Go’s stdlib but in a modern JS environment.

Goal

We need to add JSR-compatible symbol documentation to all exported functions, classes, constants, and types.

Currently, JSR shows only package-level docs because symbols lack JSDoc comments.
The goal is for each symbol to have complete, clear, and well-structured documentation so that they appear correctly in the JSR symbol pages.

Instructions

For each exported symbol (function, class, constant, or interface):

  1. Add a JSDoc comment immediately above the export.
  2. Follow the JSR Symbol Documentation Guide:
    https://jsr.io/docs/writing-docs#symbol-documentation
  3. Include:
    • A concise one-sentence summary starting with a verb.
    • @param and @returns for functions.
    • @example for at least one key symbol per file.
    • Markdown formatting for inline code or code blocks.
  4. Maintain GoDoc-like clarity and tone — short, factual, and consistent.
  5. Do not modify implementation logic.
  6. If a file lacks a top-level module comment, add one explaining the file’s purpose.

Example Format

/**
 * Returns a new string with the first character capitalized.
 * Similar to Go's strings.Title but safe for JS.
 *
 * @param s - The input string.
 * @returns A new string with the first letter capitalized.
 * @example
 * toTitle("hello") // "Hello"
 */
export function toTitle(s: string): string {
  return s.charAt(0).toUpperCase() + s.slice(1);
}

Verification

After adding documentation:

  • Run deno doc --lint locally to ensure proper structure.
  • Confirm that symbol documentation is generated on the JSR page after publishing.

Task

Start with the current file and proceed through all source files in the project.
Ensure every exported symbol has valid, JSR-compatible documentation.
</agent_instructions>

Comments on the Issue (you are @copilot in this section)


✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Copilot AI and others added 3 commits October 29, 2025 06:30
…el, bytes/buffer, bytes/search, bytes/transform)

Co-authored-by: OkutaniDaichi0106 <132345842+OkutaniDaichi0106@users.noreply.github.com>
… sync/cond, io interfaces)

Co-authored-by: OkutaniDaichi0106 <132345842+OkutaniDaichi0106@users.noreply.github.com>
…ument Closer.close method)

Co-authored-by: OkutaniDaichi0106 <132345842+OkutaniDaichi0106@users.noreply.github.com>
Copilot AI changed the title [WIP] Add symbol documentation for exported members Add JSDoc documentation for JSR symbol pages Oct 29, 2025
Copilot AI requested a review from okdaichi October 29, 2025 06:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[FEATURE] Add Symbol Documentation

2 participants

Comments